Kontext-URL

Die Kontext-URL (in der Moduloberfläche: Externe URL der UI-Integration) ist ein Deep-Link in Ihre Fachanwendung: Beim Anruf öffnet der Anwender aus dem UCC-Client heraus eine vom Modul bereitgestellte Anrufansicht, in der die von den Suchanbietern gelieferten Variablen angezeigt und in die hinterlegte URL eingesetzt werden. Ihre Anwendung muss dafür lediglich einen URL-Aufruf im Browser beantworten können — etwa die Kundenakte zu einer Kundennummer anzeigen.

Verwendung durch Dritte

Diese Schnittstelle ist für die Nutzung durch Drittsysteme freigegeben. Änderungen und Erweiterungen werden je Version in den Release Notes dokumentiert.

Grundlagen

• Typ: URL-Aufruf im Browser des Anwenders (neuer Tab bzw. Browserfenster des UCC-Clients); es findet kein Aufruf durch den STARFACE-Server statt
• Konfigurationsort: Moduloberfläche, Tab Einstellungen, Karte UI-Integration (sichtbar im Expertenmodus), Feld Externe URL
• Datenquelle: alle Parser mit aktivierter Option UI (Suchanbieter-Konfiguration → Parser/Ergebnis-Auswertung) — unabhängig davon, ob der jeweilige Suchanbieter für die reguläre Rufauflösung aktiviert ist
• Authentifizierung: keine modulseitige — die Anrufansicht läuft in der STARFACE-Sitzung des Anwenders; die Absicherung des Deep-Link-Ziels (z. B. ERP-Login, SSO) liegt bei Ihrer Anwendung
• Verfügbar seit: Modulversion 24.12.3 (UI-Integration)

Einbindung in den UCC-Client

Die Anrufansicht des Moduls binden Sie im UCC-Client unter Einstellungen → Browser → URLs / Anruf-Aktionen ein. Die fertigen URLs zeigt die Karte UI-Integration zum Kopieren an:

URL	Verwendung
Standard-URL	Einbindung als Widget (ohne Rufnummernbezug)
Anruf-Aktion-URL	Aufruf je Anruf; endet auf &phonenumber=$(callerIdCanonical)

$(callerIdCanonical) ist ein Platzhalter des UCC-Clients und wird von diesem durch die kanonische Rufnummer des Gesprächspartners ersetzt. Wann die Anruf-Aktion ausgelöst wird (eingehende Anrufe, ausgehende Anrufe, manuell), bestimmen die Einstellungen des UCC-Clients. Beide URLs enthalten den Namen der Modulkonfiguration — wird dieser umbenannt, müssen die im UCC-Client hinterlegten URLs angepasst werden.

Platzhalter

In der Externen URL verwenden Sie Platzhalter in doppelten geschweiften Klammern:

Syntax	Wird ersetzt durch
{{<bezeichnung>}}	das Ergebnis des Parsers, dessen Feld Bezeichnung dem Platzhalternamen entspricht und dessen Option UI aktiviert ist

Beispiel aus der Moduloberfläche: https://my-erp.example.com/user/{{erp-id}}.

Regeln der Ersetzung:

• Die Karte UI-Integration listet unter „Die folgenden Variablen stehen aktuell zur Verfügung" alle nutzbaren Platzhalter je Suchanbieter auf.
• Die Ersetzung ist eine reine Zeichenkettenersetzung; die Werte werden nicht URL-kodiert eingesetzt. Verwenden Sie daher bevorzugt technische Kennungen (IDs, Nummern) statt Freitext.
• Der Link wird nur angeboten, wenn alle Platzhalter der URL ersetzt werden konnten. Bleibt ein Platzhalter ohne Wert (kein Treffer, unbekannte Bezeichnung), erscheint kein Link.

Verhalten in der Anrufansicht

Beim Öffnen der Anrufansicht fragt das Modul alle Suchanbieter mit UI-Parsern parallel ab und wartet bis zu drei Sekunden auf deren Ergebnisse. Die Ansicht zeigt die aufgelösten Variablen als Tabelle (Name/Wert, mit Kopierfunktion) und — sobald alle Platzhalter ersetzt sind — die Schaltfläche „Extern öffnen", die die Kontext-URL in einem neuen Browser-Tab öffnet. Über das Menü der Schaltfläche aktiviert jeder Anwender für sich „Automatisch öffnen": Die Kontext-URL öffnet sich dann ohne Klick, einmal je Anrufansicht (Einstellung wird browser-lokal gespeichert; Standard: aus).

Ergebnisse werden zwischengespeichert: serverseitig 60 Sekunden je Rufnummer und Suchanbieter, in der Anrufansicht fünf Minuten je Rufnummer.

Beispiel: ERP-Deep-Link

Ihr ERP zeigt Kundenakten unter https://erp.example.com/kunden/<kundennummer>. Der Web-Resolver Ihres ERP-Endpunkts liefert in der Antwort das Feld "customer_id"; ein zusätzlicher Parser stellt es der UI-Integration bereit:

Einstellung	Wert
Parser-Matcher	"customer_id":"([^"]*)"
Parser-Formatter	\1
Bezeichnung	erp-id
Option UI	aktiviert

Externe URL:

https://erp.example.com/kunden/{{erp-id}}

Bei einem Anruf von +4972115104230 löst die Anruf-Aktion des UCC-Clients die Anrufansicht aus. Der Web-Resolver liefert customer_id = 10815; die Ansicht zeigt die Variable erp-id = 10815 und die Schaltfläche „Extern öffnen" führt auf:

https://erp.example.com/kunden/10815

Mit aktivierter Option „Automatisch öffnen" springt die Kundenakte ohne weiteren Klick auf — der Anwender nimmt das Gespräch an und hat den Vorgang bereits vor sich.

Anwendungsbeispiel

Ein Ticketsystem erlaubt die Vorbelegung neuer Tickets per URL-Parameter. Als Kontext-URL hinterlegt: https://tickets.example.com/new?kunde={{erp-id}}&firma={{firma}} — beide Variablen liefert derselbe Web-Resolver. Beim Anruf entsteht das vorausgefüllte Ticket mit einem Klick, ohne Copy & Paste aus der Rufliste.

Fehlerbehandlung

• Platzhalter ohne Wert: Kann ein Platzhalter nicht ersetzt werden, wird bewusst kein Link angezeigt — es öffnet sich nie eine URL mit unaufgelösten {{…}}-Bestandteilen. Prüfen Sie in der Karte UI-Integration, ob die Bezeichnung exakt übereinstimmt und die Option UI am Parser aktiv ist.
• Keine Daten: Liefert kein Suchanbieter Werte, zeigt die Anrufansicht den Hinweis „Keine Daten".
• Langsame Suchanbieter: Nach drei Sekunden bricht das Warten ab; später eintreffende Ergebnisse stehen erst beim nächsten Öffnen (innerhalb des 60-Sekunden-Caches) zur Verfügung.
• Sonderzeichen: Da Werte nicht URL-kodiert werden, können Leer- und Sonderzeichen in Variablenwerten zu fehlerhaften Ziel-URLs führen — verwenden Sie IDs statt Namen.
• Diagnose: Die den Variablen zugrunde liegenden Abfragen protokolliert der Tab Suchanfragen wie jede reguläre Auflösung.

Versionierung & Kompatibilität

Die Schnittstelle ist nicht explizit versioniert. Den stabilen Vertrag bilden die Platzhaltersyntax {{<bezeichnung>}}, die Kopplung an die UI-Option der Parser sowie das Verhalten, den Link nur bei vollständiger Ersetzung anzubieten. Die UI-Integration steht seit Modulversion 24.12.3 zur Verfügung; der Platzhalter $(callerIdCanonical) gehört zum UCC-Client der STARFACE und folgt dessen Versionierung. Änderungen dokumentieren die Release Notes der jeweiligen Modulversion.